---
name: Table (Editor's Draft)

pathToResearch: /components/table.research
showInMenu: false
layout: ../../layouts/ComponentLayout.astro
---

import TableAnatomy from '../../components/table-anatomy'

The Table component is a control that displays data to user in tabular form. Can be separated into two main types: static and dynamic tables or data grids.

Static -- tabular structure containing one or more rows that each contain one or more cells; it is not an interactive widget. Thus, its cells are not focusable or selectable. (per [WAI-ARIA](https://www.w3.org/TR/wai-aria-practices/#table))

Data grid -- tabular information that has column titles, row titles, or both and enables users to navigate interactive elements it contains using directional navigation keys. The grid pattern is particularly useful if the tabular information is editable or interactive (per [WAI-ARIA](https://www.w3.org/TR/wai-aria-practices/#grid))

## Anatomy

### Diagram

<TableAnatomy />

### Part Definitions

`::part-table` — Root element that contains header (optional) and table rows

`::part-table-header` — Container for table title

`::part-table-title` — Text description of the table

`::part-table-header-row` — Container for table header elements

`::part-table-row` — Container for table cell elements

`::part-table-header-cell` — Column header. May contain interactive elements and icons to represent sorting/filtering states

`::part-table-cell` — Table cell data. May contain interactive elements

`::part-table-footer` — Container for table pagination element

`::part-table-pagination` — Pagination control for multi-page data tables

`::part-pagination-item` — Pagination control representing the pages.

### Component attributes

TBD

## Accessibility

### Keyboard

Data grid implements the [WAI-ARIA's Keyboard Interaction For Data Grids](https://www.w3.org/TR/wai-aria-practices-1.1/#keyboard-interaction-for-data-grids).

### Assistive technology

Static table implements the [table role](https://www.w3.org/TR/core-aam-1.1/#role-map-table) per the
[HTML AAM spec](https://www.w3.org/TR/html-aam-1.0/#html-element-role-mappings).

Data grid implements the [grid role](https://www.w3.org/TR/core-aam-1.1/#role-map-grid) per the
[HTML AAM spec](https://www.w3.org/TR/html-aam-1.0/#html-element-role-mappings).

## States / Properties

### &lt;table&gt;

- **scrollable** (\_enum: none | vertical | horizontal | both): Controls whether the table content is scrollable and in what dimensions. Defaults to `none`

- **stripped** (_bool_): Controls whether the table rows should be stripped. Defaults to false

- **compact** (_bool_): Controls whether the table is displayed in compact mode. Defaults to false

### &lt;table-row&gt;

- **highlight** (_bool_): Controls whether the row should be highlighted (e.g. on hover). Defaults to false

- **selected** (_bool_): Controls whether the row is selected. Defaults to false

- **expanded** (_bool_): Controls whether the expandable row is opened. Defaults to false

- **bordered** (_bool_): Controls whether the row is bordered. Defaults to true

- **disabled** (_bool_): Controls whether can interact with a row and it's contents. Defaults to false

### &lt;table-header-row&gt;

- **fixed** (_bool_): Controls whether the header row is fixed, meaning that it always stays visible during scrolling. (`scrollable` must be set to `vertical` or `both` for the table). Defaults to false

### &lt;table-header-cell&gt;

- **sorted** (_enum: auto | asc | desc_)): Controls whether the data is sorted by column in the selected order. Defaults to auto

- **fixed** (_bool_): Controls whether the column is fixed, meaning that it always stays visible during horizontal scrolling. (`scrollable` must be set to `horizontal` or `both` for the table). Defaults to false

- **resizable** (_bool_): Controls whether the column's width can be changed by users. Defaults to false

- **onResize** (_function_): Callback function fired when the column is resized (`resizable` must be enabled).

### &lt;table-cell&gt;

- **truncated** (_bool_): Controls whether the content of the cell is truncated

- **bordered** (_bool_): Controls whether the cell is bordered. Defaults to true

- **colspan** (_number_): Specify if the cell should span across number of rows. Defaults to 1

# Resources

[WAI-ARIA `table` specification](https://www.w3.org/TR/wai-aria-practices/#table)

[WAI-ARIA `grid` specification](https://www.w3.org/TR/wai-aria-practices/#grid)

[WHATWG Living Standard on &lttable&gt](https://html.spec.whatwg.org/multipage/tables.html#the-table-element)

# Implementation research

| Framework   | Component                                                                                                                                             | Playground                                                                                           | HTML tag                      | Data ingestion                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------- |
| Carbon      | [Data table](https://www.carbondesignsystem.com/components/data-table/code/)                                                                          | [Playground](https://codepen.io/team/carbon/full/jRWbZZ/)                                            | `<table>`                     | JSON object                                                      |
| Bootstrap   | [Tables](https://getbootstrap.com/docs/5.3/content/tables/)                                                                                           | -                                                                                                    | `<table>`                     | -                                                                |
| Salesforce  | [Data table](https://www.lightningdesignsystem.com/components/data-tables/), [tree-grid](https://www.lightningdesignsystem.com/components/tree-grid/) | [Playground](https://developer.salesforce.com/docs/component-library/tools/playground)               | `<table>`                     | -                                                                |
| Material    | [Data table](https://material.io/develop/web/components/data-tables/)                                                                                 | [Demo](https://material-components.github.io/material-components-web-catalog/#/component/data-table) | `<table>`                     | -                                                                |
| Fabric UI   | [Detail list](https://developer.microsoft.com/en-us/fabric#/controls/web/detailslist)                                                                 | [Playground](https://developer.microsoft.com/en-us/fabric#/controls/web/detailslist)                 | `<div role="grid">`           | -                                                                |
| Atlaskit    | [Dynamic table](https://atlaskit.atlassian.com/packages/core/dynamic-table)                                                                           | [Playground](https://atlaskit.atlassian.com/packages/core/dynamic-table/example/stateful)            | `<table>`                     | -                                                                |
| Ant         | [Table](https://ant.design/components/table/)                                                                                                         | [Playground](https://ant.design/components/table/)                                                   | `<table>`                     | JSON object, with custom render function defined at column level |
| Auth0       | [Table](https://styleguide.auth0.com/components/tables)                                                                                               | -                                                                                                    | `<table>`                     | -                                                                |
| Evergreen   | [Table](https://evergreen.segment.com/components/table)                                                                                               | [Playground](https://codesandbox.io/s/evergreen-playground-component-fjbly)                          | `<div>`                       | -                                                                |
| KoliBri     | [Table](https://public-ui.github.io/docs/components/table)                                                                                            | [Playground](https://codesandbox.io/s/kolibri-public-ui-react-samples-w5u37c)                        | `<table>`                     | JSON object, with custom render function defined at column level |
| Semantic UI | [Table](https://semantic-ui.com/collections/table.html)                                                                                               | [Playground](https://jsfiddle.net/ca0rovs3/)                                                         | `<table>`                     | -                                                                |
| Aria        | [Data grid](https://www.w3.org/TR/wai-aria-practices/examples/grid/dataGrids.html), [Table](https://www.w3.org/TR/wai-aria-practices/#table)          | -                                                                                                    | `<div role="grid">`,`<table>` | -                                                                |
